home *** CD-ROM | disk | FTP | other *** search
/ HPAVC / HPAVC CD-ROM.iso / pc / ELYVER10.ZIP / MIKXMAS.ZIP / docs / mloader.doc < prev    next >
Encoding:
Text File  |  1995-11-20  |  6.2 KB  |  201 lines
  1. ┌──────────────────────────────┐
  2. │MLOADER.C Module Documentation│
  3. └──────────────────────────────┘
  4.  
  5. Date last modified: October 20, 1995
  6.  
  7. MLOADER.C uses 2 routines of the MDRIVER.C module (MD_SampleLoad() & 
  8. MD_SampleUnLoad()) so if you want to use MLOADER without using MDRIVER you'll 
  9. have to define those two routines yourself. (see MIKCVT.C as an example on 
  10. how to do that).
  11.  
  12. ════════════════════════════════════════════════════════════════════════════════
  13.  
  14. General information:
  15.  
  16. When you're making a modplayer that has to support several different formats
  17. the best thing to do is to create your own internal module-format. In 
  18. MikMod's case this is the 'UNI' format. The loader module takes care of
  19. loading any of the known module formats and converting it into a UNI format.
  20.                                           
  21.             ┌───────────────┬─────────────────────────────┐
  22.             │LOADER BLACKBOX│                             │
  23.             ├───────────────┘                             │
  24.             │    ┌──────────┐                             │
  25.             │ ┌──┤mod loader├──┐                          │
  26.             │ │  └──────────┘  │                          │
  27.             │ │  ┌──────────┐  │                          │
  28.             │ ├──┤ult loader├──┤                          │
  29.             │ │  └──────────┘  │                          │
  30.             │ │  ┌──────────┐  │                          │
  31.             │ ╔══┤s3m loader├══╗ <- appropriate loader    │
  32.             │ ║  └──────────┘  ║    for this file         │
  33.             │ ║  ┌──────────┐  ║                          │
  34.             │ ║──┤uni loader├──║                          │
  35.             │ ║  └──────────┘  ║                          │
  36.             │ ║  ┌──────────┐  ║                          │
  37.             │ ║──┤mtm loader├──║                          │
  38.             │ ║  └──────────┘  ║                          │
  39.             │ ║  ┌──────────┐  ║  ┌─────────────────────┐ │
  40.  modfile >════╝──┤med loader├──╚══┤LOADER GLUE FUNCTIONS├─┼──>>─ unimod *
  41.             │ │  └──────────┘  │  └─────────────────────┘ │
  42.             │ │  ┌──────────┐  │                          │
  43.             │ ├──┤xm  loader├──┤                          │
  44.             │ │  └──────────┘  │                          │
  45.             │ │  ┌──────────┐  │                          │
  46.             │ ├──┤669 loader├──┤    - common loader       │
  47.             │ │  └──────────┘  │      routines            │
  48.             │ │  ┌──────────┐  │                          │
  49.             │ ├──┤far loader├──┤    - common loader       │
  50.             │ │  └──────────┘  │      variables           │
  51.             │ │  ┌──────────┐  │                          │
  52.             │ ├──┤dsm loader├──┤                          │
  53.             │ │  └──────────┘  │                          │
  54.             │ │  ┌──────────┐  │                          │
  55.             │ └──┤... loader├──┘                          │
  56.             │    └──────────┘                             │
  57.             │                                             │
  58.             └─────────────────────────────────────────────┘
  59.             
  60. To prevent having to link _all_ loaders to the loader module when you only 
  61. wanted to use the uni-loader, for example), the first thing the main module 
  62. has to do before using the loader module is to 'register' all loaders it 
  63. might need. This way only the registered drivers will get linked to the 
  64. executable.
  65.     
  66. ════════════════════════════════════════════════════════════════════════════════
  67.  
  68. void ML_RegisterLoader(LOADER *ldr)
  69. ===================================
  70.  
  71. Input parms:
  72.  
  73.     ldr     pointer to a LOADER structure
  74.  
  75.  
  76. Returns:
  77.  
  78.     -
  79.  
  80.  
  81. Description:
  82.  
  83. Before you can load any modules (with ML_LoadFN() or ML_LoadFP()) you first 
  84. have to register the loaders you want to use. This way only the registered 
  85. loaders are linked to the resulting program, so if you only wanted to support 
  86. a single format your program won't be so big.
  87.  
  88.  
  89. Example:
  90.  
  91.     [ at the start of the main program: ]
  92.  
  93.     {
  94.         ...
  95.  
  96.         ML_RegisterLoader(&modload);
  97.         ML_RegisterLoader(&uniload);
  98.  
  99.         ML_InfoLoader();
  100.         ...
  101.         ...
  102.  
  103.     }
  104.  
  105. (if you want to keep your program as small as possible, only use the .UNI 
  106. loader since it is the smallest loader available (go figure!) )
  107.  
  108. ════════════════════════════════════════════════════════════════════════════════
  109.  
  110. void ML_InfoLoader(void)
  111. ========================
  112.  
  113. Input parms:
  114.  
  115.     -
  116.  
  117.  
  118. Returns:
  119.  
  120.     -
  121.  
  122.  
  123. Description:
  124.  
  125. This function produces a list of all registered loader modules to stdout. Use 
  126. it _after_ you've registered all loaders using ML_RegisterLoader().
  127.  
  128. ════════════════════════════════════════════════════════════════════════════════
  129.  
  130. UNIMOD *ML_LoadFP(FILE *fp)
  131. ===========================
  132.  
  133. Input parms:
  134.  
  135.     fp    filepointer to a music module
  136.  
  137.  
  138. Returns:
  139.  
  140.     A pointer to a UNIMOD structure
  141.  
  142.     or
  143.  
  144.     NULL if an error occured during loading.
  145.  
  146.  
  147. Description:
  148.  
  149. With this routine you can load a music-module by it's file-pointer. If it 
  150. returns NULL, print myerr (MMIO.C) to see what went wrong. This routine 
  151. doesn't close the filepointer when it's done, but you can't rely on it still 
  152. having the same file-position. Use ML_Free() to free the UNIMOD when you're 
  153. done with it.
  154.  
  155. ════════════════════════════════════════════════════════════════════════════════
  156.  
  157. void ML_Free(UNIMOD *mf)
  158. ========================
  159.  
  160. Input parms:
  161.  
  162.     mf    pointer to a UNIMOD structure
  163.  
  164.  
  165. Returns:
  166.  
  167.     -
  168.  
  169.  
  170. Description:
  171.  
  172. Use this routine to free the module you loaded with ML_LoadFN() or 
  173. ML_LoadFP().
  174.  
  175. ════════════════════════════════════════════════════════════════════════════════
  176.  
  177. UNIMOD *ML_LoadFN(char *filename)
  178. =================================
  179.  
  180. Input parms:
  181.  
  182.     filename        The filename of the module you want to load.
  183.  
  184.  
  185. Returns:
  186.  
  187.     A pointer to a UNIMOD structure
  188.  
  189.     or
  190.  
  191.     NULL if an error occured during loading.
  192.  
  193.  
  194. Description:
  195.  
  196. With this routine you can load a music-module by it's filename. If it returns 
  197. NULL, print myerr (MERROR.C) to see what went wrong. Use ML_Free() to free 
  198. the UNIMOD when you're done with it.
  199.  
  200. ════════════════════════════════════════════════════════════════════════════════
  201.